edocs Home > BEA AquaLogic Data Services Platform 3.0/3.2 Documentation > ALDSP 3.2 New Features Documentation

Mutator Functions

This topic describes the built-in mutator functions available in ALDSP 3.2.

ALDSP uses the Extended XQuery Data Model (XXDM), an extension of the XQuery Data Model (XDM), to represent instances of the XDM along with information about changes to the instances.

fn-bea:changed-element

The fn-bea:changed-element() function allows you to promote an element to an unmodified changed-element. You can then modify the resulting changed-element using the built-in mutator functions.

The fn-bea:changed-element() function has the following signature:

fn-bea:changed-element($e as element()) as changed-element()

Example 

The following call declares $cc to be an unmodified changed-element of type customer for the element represented by $c. 

declare $cc as changed-element(customer) := fn-bea:changed-element($c);

fn-bea:insert-into

The fn-bea:insert-into() function enables you to insert a node into an XXDM instance at a specified XPath location.

The fn-bea:insert-into() function has the following signature:

fn-bea:insert-into($ce as changed-element(),
                   $path as xs:string,
                   $value as node()) as changed-element()

where

• $ce is the XXDM instance to be modified
• $path specifies a path into $ce using an SDO XPath fragment
• $value contains the node that is to be inserted

Examples 

Consider the changed-element customer that has the following value bound to the variable $cc:

<customer ssn="XXX-XX-XXX">
   <name>
      <first>Thomas</first>
      <last>Smith</last>
   </name>
   <address>...</address>
   <address>...</address>
   <orders>
      <order>...</order>
      <order>...</order>
   <orders>
<customer>

Example - Inserting a New Element

 Consider the following call:

set $cc := fn-bea:insert-into($cc, "name", <middle>Paul</middle>);

Assuming that the schema for customer permits an element for the middle name (middle) as a child of name and between the elements first and last, the call inserts the middle element as follows:

<customer ssn="XXX-XX-XXX">
   <name>
      <first>Thomas</first>
      <middle>Paul</middle>
      <last>Smith</last>
   </name>
...
<customer>

Example - Inserting an Additional Element 

Consider the following call:

set $cc := fn-bea:insert-into($cc, ".", <address>...<city>York</city></address>);

The call inserts an additional address element into the customer element, as follows:

<customer ssn="XXX-XX-XXX">
   <name>...</name>
   <address>...</address>
   <address>...<city>York</city></address>
   <address>...</address>
   <orders>...</orders>
<customer>

Example - Inserting an Attribute

Consider the following call:

set $cc := fn-bea:insert-into($cc, "orders/order[2]", attribute paid { fn:true() });

The call inserts the paid attribute into the second order, as shown by the following.

<customer ssn="XXX-XX-XXX">
   ...
   <orders>
      <order>...</order>
      <order paid="true">...</order>
   <orders>
<customer>

fn-bea:delete

The fn-bea:delete() function enables you to delete a node at a specified XPath location in an XXDM instance. The function returns a copy of the instance that does not contain the specified descendant.

The fn-bea:delete() function has the following signature:

fn-bea:delete($ce as changed-element(),
              $path as xs:string) as changed-element()

where:

• $ce is the XXDM instance to be modified
• $path uniquely specifies a path to the descendant node of $ce that is to be deleted using the SDO XPath fragment

Examples 

Assume that the variable $cust is bound to the value presented in the earlier example.

Example - Deleting an Element

Consider the following call:

set $cc := fn-bea:delete($cc, "address[2]");

The call deletes the second address child element of $cust, resulting in the value shown in the following:

<customer ssn="XXX-XX-XXX">
   <name>...</name>
   <address>...</address>
   <orders>...<orders>
<customer>

Example - Deleting an Attribute

Consider the following call:

set $cc := fn-bea:delete($cc, "@ssn");

The call deletes the ssn attribute of $cust, resulting in the value shown in the following:

<customer>
<name>...</name>
<address>...</address>
<address>...</address>
<orders>...<orders>
<customer>

fn-bea:replace-value

The fn-bea:replace-value() function enables you to replace the value of a node in an XXDM instance at a specified XPath location. The function returns a copy of the instance containing the replaced value.

The fn-bea:replace-value() function has the following signature:

fn-bea:replace-value($ce as changed-element(),
                     $path as xs:string,
                     $value as xdt:anyAtomicType*) as changed-element()

where:

• $ce is the XXDM instance to be modified
• $path uniquely specifies a path to the descendant node of $ce that is to be modified using the SDO XPath fragment
• $value contains the value that is to replace the value of the targeted node

  The function raises an error if the target node does not have simple content.

Examples 

Assume that the variable $cc is bound to the value presented in the earlier example.

Example - Replacing the Contents of an Element

Consider the following call:

set $cc := fn-bea:replace-value($cc, "name/last", "Jones");

The call changes the content of the last child of name from Smith to Jones, as shown in the following:

<customer ssn="XXX-XX-XXX">
<name>
   <first>Thomas</first>
   <last>Jones</last>
</name>
...
<customer>

Example - Replacing an Attribute Value

Consider the following call:

set $cc := fn-bea:replace-value($cc, "@ssn", "YYY-YY-YYYY");

The call changes the content of the ssn attribute from XXX-XX-XXX to YYY-YY-YYYY, as shown in the following:

<customer ssn="YYY-YY-YYYY">
<name>...</name>
<address>...</address>
<address>...</address>
<orders>...<orders>
<customer>

Example - Removing the Contents of an Element

Consider the following call:

set $cc := fn-bea:replace-value($cc, "name/first", ());

The call removes the content of the first child element of name, as shown in the following:

<customer ssn="XXX-XX-XXX">
<name>
   <first/>
   <last>Smith</last>
</name>
...
<customer>

If the element first is nillable, the result would be nilled, as shown in the following:

<customer ssn="XXX-XX-XXX">
<name>
   <first xsi:nil="true"/>
   <last>Smith</last>
</name>
...
<customer>

See Also

Concepts

•   Mutators for Updates

How Tos

•   Modify Instances Using Mutator Functions

Reference

•   Mutator Function Examples